Crate netcdf

Rust bindings for Unidata’s libnetcdf

This crate allows one to store and retrieve multi-dimensional arrays from a netCDF supported format, which can be a netCDF file, a subset of hdf5 files, or from a DAP url.

netCDF files are self-contained, they contain metadata about the data contained in them. See the CF Conventions for conventions used for climate and forecast models.

To explore the documentation, see the Functions section, in particular open(), create(), and append().

For more information see:

• The official introduction to netCDF
• The netCDF-c repository

Examples

How to read a variable from a file:

// Open the file `simple_xy.nc`:
let file = netcdf::open("simple_xy.nc")?;

// Get the variable in this file with the name "data"
let var = &file.variable("data").expect("Could not find variable 'data'");

// Read a single datapoint from a 1D variable as a numeric type
let data_i32 = var.value::<i32, _>(4)?;
let data_f32 : f32 = var.value(5)?;

// If your variable is multi-dimensional you need to use a
// type that supports `Selection`, such as a tuple or array
let data_i32 = var.value::<i32, _>([40, 0, 0])?;
let data_i32 = var.value::<i32, _>((40, 0, 0))?;

// You can use `values_arr()` to get all the data from the variable.
// Passing `..` will give you the entire slice
let data = var.values_arr::<i32, _>(..)?;

// A subset can also be selected, the following will extract the slice at
// `(40, 0, 0)` and get a dataset of size `100, 100` from this
let data = var.values_arr::<i32, _>(([40, 0 ,0], [1, 100, 100]))?;
let data = var.values_arr::<i32, _>((40, ..100, ..100))?;

How to create a new file and write to it:

// Create a new file with default settings
let mut file = netcdf::create("crabs.nc")?;

// We must create a dimension which corresponds to our data
file.add_dimension("ncrabs", 10)?;
// These dimensions can also be unlimited and will be resized when writing
file.add_unlimited_dimension("time")?;

// A variable can now be declared, and must be created from the dimension names.
let mut var = file.add_variable::<i32>(
            "crab_coolness_level",
            &["time", "ncrabs"],
)?;
// Metadata can be added to the variable
var.add_attribute("units", "Kelvin")?;
var.add_attribute("add_offset", 273.15_f32)?;

// Data can then be created and added to the variable
let data : Vec<i32> = vec![42; 10];
var.put_values(&data, (0, ..))?;

// Values can be added along the unlimited dimension, which
// resizes along the `time` axis
var.put_values(&data, (11, ..))?;

Re-exports

• pub use attribute::*;
• pub use dimension::*;
• pub use file::*;
• pub use group::*;
• pub use variable::*;

Modules

• attribute
  Add and read attributes from netcdf groups and variables
• dimension
  Interact with netcdf dimensions
• error
  Errors that can appear when interacting with netcdf files. This module contains conversion traits and the result type used in this crate.
• extent
  Extents used for putting and getting data from a variable
• file
  Open, create, and append netcdf files
• group
  All netcdf items belong in the root group, which can be interacted with to get the underlying data
• types
  Contains functions and enums describing variable types
• variable
  Variables in the netcdf file

Functions

• append
  Open a netCDF file in append mode
• append_with
  Open a netCDF file in append mode with the given options
• create
  Open a netcdf file in create mode
• create_with
  Open a netCDF file in create mode with the given options
• open
  Open a netCDF file in read mode
• open_with
  Open a netCDF file in read mode with the given options